/*
 * VHBaseDataService.java
 * Created on 29 mai 2009
 *
 * VirtualHockey Internet Platform
 * http://code.google.com/p/virtualhockey/
 *
 * Copyright (c) 2005-2009, Jens and Jan Janke (VirtualHockey Project)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see http://www.gnu.org/licenses/.
 */

package com.hockeo.vhweb.client.rpc;

import java.util.List;
import java.util.Map;

import com.extjs.gxt.ui.client.data.PagingLoadConfig;
import com.extjs.gxt.ui.client.data.PagingLoadResult;
import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;
import com.hockeo.vhweb.client.utils.VHJsData;
import com.hockeo.vhweb.client.utils.VHServerException;
import com.hockeo.vhweb.client.utils.enums.VHJsClubContestHistoryType;
import com.hockeo.vhweb.client.utils.enums.VHJsStandingsType;

/**
 * Service providing access to base data on the server.
 *
 * @version $Id$
 * @author jjanke
 */
@RemoteServiceRelativePath( "basedata.rpc" )
public interface VHBaseDataService extends RemoteService
{
  /**
   * Returns the club/contest history records for the given contest and season.
   *
   * @param strLocale the current locale
   * @param strContestId the ID of the contest for which to retrieve the history records
   * @param nSeasonId the ID of the season for which to retrieve the history records or
   *          <code>null</code> to retrieve the history records for the currently active
   *          season
   * @return list of contest history records
   * @throws VHServerException
   */
  public List<VHJsData> getClubContestHistoryRecords( String strLocale, String strContestId, Integer nSeasonId )
      throws VHServerException;

  /**
   * Returns the club/contest history records for the given club and competition. Returns
   * all records that so far exist.
   *
   * @param strLocale the current locale
   * @param strClubId the ID of the club for which to retrieve the records
   * @param type the type of contest records to retrieve
   * @return a list of all existing contest history records for the given club and contest
   *         type
   * @throws VHServerException
   */
  public List<VHJsData> getClubContestHistoryRecords( String strLocale, String strClubId,
      VHJsClubContestHistoryType type ) throws VHServerException;

  /**
   * Returns all club/season summary objects that so far exist for the given club.
   *
   * @param strLocale the current locale
   * @param strClubId the ID of the club for which to retrieve the records
   * @return a list of season summary objects
   * @throws VHServerException
   */
  public List<VHJsData> getClubSeasonSummaries( String strLocale, String strClubId ) throws VHServerException;

  /**
   * Returns an object representing the club with the given ID.
   *
   * @param strLocale the current locale
   * @param strClubId the ID of the club to be retrieved
   * @return the matching club
   * @throws VHServerException
   */
  public VHJsData getClub( String strLocale, String strClubId ) throws VHServerException;

  /**
   * Returns an object representing the national association with the given ID.
   *
   * @param strLocale the current locale
   * @param strAssocId the ID of the association to be retrieved
   * @return the matching association
   * @throws VHServerException
   */
  public VHJsData getNationalAssociation( String strLocale, String strAssocId ) throws VHServerException;

  /**
   * Returns a list of clubs belonging to the league whose ID is specified.
   *
   * @param strLocale the current locale
   * @param strLeagueId the ID of the league for which to retrieve all clubs
   * @return list of clubs
   * @throws VHServerException
   */
  public List<VHJsData> getClubsForLeague( String strLocale, String strLeagueId ) throws VHServerException;

  /**
   * Returns a list of all contest history records that exist for the given contest
   *
   * @param strLocale the current locale
   * @param strContestId the ID of the contest for which to retrieve the history records
   * @return list of contest history records
   * @throws VHServerException
   */
  public List<VHJsData> getContestHistoryRecords( String strLocale, String strContestId ) throws VHServerException;

  /**
   * Returns a list of contest history records of all major international and national
   * contests.
   *
   * @param strLocale the current locale
   * @param nSeasonId the ID of the season for which to search results (<code>null</code>
   *          to retrieve data for the current season)
   * @return list of contest history objects
   * @throws VHServerException
   */
  public List<VHJsData> getAllMajorContestHistoryRecords( String strLocale, Integer nSeasonId )
      throws VHServerException;

  /**
   * Returns a list of contest elements associated with the given contest round.
   *
   * @param strLocale the current locale
   * @param strRoundId the ID of the contest round for which to return the contest
   *          elements
   * @return list of contest elements
   * @throws VHServerException
   */
  public List<VHJsData> getContestElements( String strLocale, String strRoundId ) throws VHServerException;

  /**
   * Returns a list of all rounds of the given contest.
   *
   * @param strLocale the current locale
   * @param strContestId the ID of the contest for which to retrieve the rounds
   * @return list of contest rounds
   * @throws VHServerException
   */
  public List<VHJsData> getContestRounds( String strLocale, String strContestId ) throws VHServerException;

  /**
   * Returns a list of all countries that are available in VH.
   */
  public List<VHJsData> getCountries( String strLocale ) throws VHServerException;

  /**
   * Returns the following contest history records that can be used to build a country
   * (national association) specific season overview:
   *
   * <ul>
   * <li>The top 3 ranked clubs from the national cup.</li>
   * <li>All clubs that have qualified for international contests, got promoted or
   * relegated from the national leagues.</li>
   * <li>All clubs that have been qualified for international contests during the given
   * season.</li>
   * </ul>
   *
   * @param strLocale the current locale
   * @param strAssocId the ID of the association for which to retrieve the results
   * @param nSeasonId the ID of the season for which to search results
   * @return a list of club/history records
   * @throws VHServerException
   */
  public List<VHJsData> getCountrySeasonOverviewRecords( String strLocale, String strAssocId, Integer nSeasonId )
      throws VHServerException;

  /**
   * Returns a map that contains the current information about the club's league, cup, CL
   * and WL results/standings.
   *
   * @param strLocale the current locale
   * @param strClubId the ID of the club for which to return data
   * @return a map where the current results are mapped to the keys 'league', 'cup', 'cl',
   *         'wl' and 'ecr'
   * @throws VHServerException
   */
  public Map<String, VHJsData> getCurrentClubSituation( String strLocale, String strClubId ) throws VHServerException;

  /**
   * Retrieves eternal standings in such a form that they can be used with components
   * using paging. All the sorting and page handling is done on the server side.
   *
   * @param cfg the paging load config indicating which is the first element to be
   *          retrieved etc.
   * @param strLocale the current locale
   * @param strElementId the ID of the contest element for which to retrieve eternal
   *          standings
   * @return paging load results
   * @throws VHServerException
   */
  public PagingLoadResult<VHJsData> getEternalStandings( PagingLoadConfig cfg, String strLocale, String strElementId )
      throws VHServerException;

  /**
   * Retrieves ECR standings in such a form that they can be used with components using
   * paging. All the sorting and page handling is done on the server side.
   *
   * @param cfg the paging load config indicating which is the first element to be
   *          retrieved etc.
   * @param strLocale the current locale
   * @param nSeasonId the season for which to retrieve the standings, if <code>null</code>
   *          the data for the currently active season is retrieved
   * @param strAssocId the association for which to retrieve the standings,
   *          <code>null</code> to retrieve all standings
   * @return paging load results
   * @throws VHServerException
   */
  public PagingLoadResult<VHJsData> getECRStandings( PagingLoadConfig cfg, String strLocale, Integer nSeasonId,
      String strAssocId ) throws VHServerException;

  /**
   * Retrieves all ENR standings of the given season.
   *
   * @param strLocale the current locale
   * @param nSeasonId the season for which to retrieve the standings, if <code>null</code>
   *          the data for the currently active season is retrieved
   * @return a list of Earth Nation Ranking standings
   * @throws VHServerException
   */
  public List<VHJsData> getENRStandings( String strLocale, Integer nSeasonId ) throws VHServerException;

  /**
   * Retrieves historic end of season standings.
   *
   * @param strLocale the current locale
   * @param strElementId the ID of the contest element for which to retrieve historic
   *          standings
   * @param nSeasonId the ID of the season for which to retrieve standings, pass in
   *          <code>null</code> to retrieve data for the currently active season
   * @param standingsType the type of standings to be retrieved
   * @return a list of archived historic standings
   * @throws VHServerException
   */
  public List<VHJsData> getHistoricStandings( String strLocale, String strElementId, Integer nSeasonId,
      VHJsStandingsType standingsType ) throws VHServerException;

  /**
   * Retrieves the international competitions.
   *
   * @param strLocale the current locale
   * @return list of international contests
   * @throws VHServerException
   */
  public List<VHJsData> getInternationalContests( String strLocale ) throws VHServerException;

  /**
   * Returns a list of all leagues in the specified country.
   *
   * @param strAssocId the ID of the association for which to return all leagues
   */
  public List<VHJsData> getLeagues( String strLocale, String strAssocId ) throws VHServerException;

  /**
   * Retrieves all KO matches for the given contest and round. If the round ID is null,
   * the matches of the currently active round are returned.
   *
   * @param strLocale the current locale
   * @param strContestId the ID of the contest for which to retrieve matches
   * @param strRoundId the ID of the round or <code>null</code> to retrieve matches of the
   *          current round
   * @return list of KO matches
   * @throws VHServerException
   */
  public List<VHJsData> getKOMatches( String strLocale, String strContestId, String strRoundId )
      throws VHServerException;

  /**
   * Retrieves all matchdays of the round robin element whose ID is specified.
   *
   * @param strLocale the current locale
   * @param strElementId the ID of the element for which to retrieve the matchdays
   * @return list of matchdays
   * @throws VHServerException
   */
  public List<VHJsData> getMatchdays( String strLocale, String strElementId ) throws VHServerException;

  /**
   * Returns all matches of the current season for the given club.
   *
   * @param strLocale the current locale
   * @param strClubId the ID of the club for which to retrieve matches
   * @return a list of matches
   * @throws VHServerException
   */
  public List<VHJsData> getMatchesForClub( String strLocale, String strClubId ) throws VHServerException;

  /**
   * Returns all matches for the given element.
   *
   * @param strLocale the current locale
   * @param strElementId the ID of the contest element for which to retrieve the matches
   * @return list of matches
   * @throws VHServerException
   */
  public List<VHJsData> getMatches( String strLocale, String strElementId ) throws VHServerException;

  /**
   * Returns the matches for the given element/matchday combination.
   *
   * @param strLocale the current locale
   * @param strElementId the ID of the contest element for which to retrieve the matches
   * @param nMatchday the matchday for which to retrieve standings (<code>null</code> to
   *          retrieve the matches of the last played matchday)
   * @return list of matches
   * @throws VHServerException
   */
  public List<VHJsData> getMatches( String strLocale, String strElementId, Integer nMatchday ) throws VHServerException;

  /**
   * Returns all the seasons (until the currently active one). Each season's data
   * availability flag indicates whether club/contest history data is available or not for
   * the season.
   *
   * @param strLocale the current locale
   * @param strContestId the contest for which to check data availability
   * @return a list of seasons
   * @throws VHServerException
   */
  public List<VHJsData> getSeasonsForClubHistory( String strLocale, String strContestId ) throws VHServerException;

  /**
   * Returns all the seasons (until the currently active one). Each season's data
   * availability flag indicates whether international ranking data is available or not
   * for the season.
   *
   * @param strLocale the current locale
   * @return a list of seasons
   * @throws VHServerException
   */
  public List<VHJsData> getSeasonsForIntRankings( String strLocale ) throws VHServerException;

  /**
   * Returns a list of standings for the given round robin contest element.
   *
   * @param strElementId the ID of the element for which to retrieve standings
   * @param standingsType the type of standings to be retrieved
   * @param nMatchday the matchday for which to retrieve standings or <code>null</code>
   * @return list of standings
   * @throws VHServerException
   */
  public List<VHJsData> getStandings( String strLocale, String strElementId, VHJsStandingsType standingsType,
      Integer nMatchday ) throws VHServerException;
}
